Aalto Version: Pikaopas

Aalto-yliopiston yhteinen versionhallintajärjestelmä ohjelmistokehitykseen palvelee osoitteessa https://version.aalto.fi

• Sisäänkirjautuminen
• Uuden projektin lisääminen
• Kirjautuminen SSH:lla
• Tietokoneeseen tehtävät asetukset
• Isojen tiedostojen käsittely
• Lisää Git-ohjeita

Sisäänkirjautuminen

Sekä Aalto-yliopiston että muiden Haka-luottamusverkoston jäsenorganisaatioiden käyttäjät voivat kirjautua palveluun selaimella oman organisaation tunnuksillaan ( Kuva 1). Muut ulkopuoliset käyttäjät tarvitsevat erillisen tunnuksen ja salasanan, jotka syötetään kirjautumisruudun Standard-välilehdelle (Kuva 2).

Uuden projektin lisääminen

Ensimmäisen kirjautumisen jälkeen näkyville tulee aloitussivu, josta käsin voi aloittaa uuden projektin tai selata olemassa olevia, käyttäjälle näkyviä projekteja.

Aalto-yliopiston ulkopuoliset käyttäjät eivät voi lisätä projekteja.

1. Luo uusi projekti klikkaamalla New Project.
2. Syötä aukeavaan ruutuun (Kuva 3) projektin nimi, kuvaus ja aseta käyttöoikeusrajoitus (Visibility Level). Tätä toimintoa käyttämällä voit myös tuoda koodin tai projektin toisesta järjestelmästä (Import project –välilehti).
3. Klikkaa Create Project. Uusi projekti on nyt luotu.

Kirjautuminen SSH:lla

Versionhallintajärjestelmää voi käyttää SSH:lla Aalto-tunnuksella tai SSH-avaimilla. Jatkuvassa käytössä SSH-avain on kätevä ja yksityiskohtainen ohje sen luomiseksi löytyy täältä: https://version.aalto.fi/gitlab/help/user/ssh.md

HUOM! Palvelimen ssh-avaimet vaihtuivat 20.12.2021. Vanhat avaimet on poistettava ssh:n konfiguraatiotiedostosta (.ssh/known_hosts), esimerkiksi näin:

• Käytä komentoa:
  ssh-keygen -f "~/.ssh/known_hosts" -R "version.aalto.fi"
  Tarkista, että parametrille -f tulee known_hosts tiedoston oikea polku.
• Tai avaa known_hosts tiedosto tekstieditorilla ja poista version.aalto.fi -palvelimen rivi tiedostosta.

SSH-avainten sormenjäljet palvelimen version.aalto.fi identiteetin tarkastamiseksi ovat:

Tietokoneeseen tehtävät asetukset

Versionhallinnan tehokas käyttö edellyttää Git-ohjelmiston asentamista käyttämääsi koneeseen.

Aallon linux-palvelimilla Git on valmiina. Windows-työasemiin voi asentaa itseasennusportaalin (Software SelfServicePortal) kautta ohjelmistopaketin SW_Git_Aalto.

Git-ohjelmistolla voit käyttää versionhallintajärjestelmää https-yhteydellä Aalto-tunnuksilla näin:

• Käyttäjätunnus muodossa: tunnus@aalto.fi
• Salasana: Aalto-tunnuksesi salasana

Paikallinen hakemisto

Koodi on paikallisessa hakemistossa ja versionhallintajärjestelmässä. Käytä paikallisena hakemistona tietokoneen levyllä olevaa kansiota tai Aallon verkkolevyä (home / work / teamwork). OneDrive-palveluun synkronoitu hakemisto ei toimi git:n kanssa luotettavasti, vaan versionhallinta rikkoutuu herkästi. Paikallisesta hakemistosta ei välttämättä tarvita varmuuskopiotakaan, sillä koodista on palvelinkopio versionhallintajärjestelmässä.

Asetukset koneelle komentoriviä käyttäen:

Huom! Löydät nämä komennot helposti oman projektisi etusivulta (https://version.aalto.fi/gitlab/<käyttäjätunnus>/<projektin-nimi>)

Yleiset asetukset, liitetään päivityksiin (commit)

git config --global user.name "Etunimi Sukunimi"

git config --global user.email "etunimi.sukunimi@aalto.fi"

Lataa projektin tiedostot koneelle ja lisää siihen README-tiedosto

git clone git@version.aalto.fi:tunnus/projektin-nimi.git

cd projektin-nimi

touch README.md

git add README.md

git commit -m "add README"

git push -u origin master

Lataa projektin tiedostot koneelle jo olemassa olevaan kansioon

cd existing_folder

git init

git remote add origin git@version.aalto.fi:tunnus/projektin-nimi.git

git add .

git commit -m "Initial commit"

git push -u origin master

Vie paikallisen Git-hakemiston (repo) tiedot uuteen projektiin version.aalto.fi:ssä

cd existing_repo

git remote rename origin old-origin

git remote add origin git@version.aalto.fi:tunnus/projektin-nimi.git

git push -u origin --all

git push -u origin --tags

Isojen tiedostojen käsittely

Versionhallintajärjestelmä ei sellaisenaan sovi suurten tiedostojen tallennukseen. Järjestelmän toiminnan takaamiseksi suurin push-operaatiossa sallittu tiedostokoko on 100 MB. Mikäli isoja tiedostoja täytyy sisällyttää versionhallintaan, käytä Git LFS -työkalua. Työkalu kirjaa versiohistoriaan tiedoston sijaan vain pointterin, jolloin projektin tilan- ja resurssientarve pienenee huomattavasti ja toiminta on tehokasta kaikille.

# Asenna Git LFS (konekohtainen)
git lfs install

# Seuraa tyypillisiä suuria binäärejä (esimerkkejä)
git lfs track "*.zip" "*.mp4" "*.pdf" "*.h5" "*.pt" "*.onnx" "*.pickle"

# Commitoi päivitetty .gitattributes
git add .gitattributes
git commit -m "Seurataan suuria tiedostoja Git LFS:llä"
git push

Tiedostojen poistaminen versiohistoriasta

Jos olet lisännyt suuria tiedostoja repositorioon normaaliin tapaan, poista ne versiohistoriasta. Tähän on usea tapa, hyviä vaihtoehtoja ovat:

• Git LFS migrate -komento, joka muuttaa isot tiedostot Git LFS -tiedostoiksi ja kirjoittaa versiohistorian uudelleen. Hyödyllinen tapa, jos tarvitset isoja tiedostoja projektissasi koodin yhteydessä.

# Ota varmuuskopio tai käytä tuoretta kloonia
# Siirrä valitut tiedostotyypit LFS:ään (muokkaa tiedostomuodot tarpeisiisi sopiviksi)
git lfs migrate import --include="*.zip,*.mp4,*.h5,*.pt,*.onnx,*.pdf"

# Force-push päivitetty historia (sovi muiden repon käyttäjien kanssa)
git push --force --all
git push --force --tags

• Tiedostojen poistaminen git-filter-repo -työkalun avulla. Hyvä vaihtoehto silloin, kun pystyt säilyttämään isot tiedostot versionhallintajärjestelmän ulkopuolella (esim. jaetulla verkkolevyllä tai Teams-palvelussa).
• Tiedosto-objektien (blob) poistaminen. Tätä varten tarvitset blob ID:t, jotka voit selvittää esim. komennolla "git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectsize:disk) %(objectname) %(rest)' | sort -k2n |tail -20" tai git ls-tree (ks. ohje edellisestä linkistä). Tiedostot poistuvat palvelimelta, jonka lisäksi ne on siirrettävä pois lokaalista repositoriosta. Voit esimerkiksi ottaa puhtaan kloonin palvelimelta toiseen kansioon ja lisätä siihen lokaalista kopiosta tarpeelliset isot tiedostot Git LFS-työkalulla.

Uusi aloitus tyhjällä projektilla

Helpoin tapa jatkaa ilman isoja tiedostoja on luoda uusi projekti, johon ei siirretä lainkaan isoja tiedostoja vaan pelkkä koodi. Tämä kuitenkin aloittaa versiohistorian alusta, jolloin aiempiin muutoksiin ei voida palata. Luo uusi kansio, kopioi sinne pelkät kooditiedostot ja luo sitten uusi projekti, johon viet tiedosto uudessa kansiossa (ks. yllä kohta "Lataa projektin tiedostot koneelle jo olemassa olevaan kansioon").

Gitlab APIn käyttö

Gitlab Free -tason API-rajapinnan toiminnot ovat käytettävissä. Huom. rajapinnan osoite sisältää /gitlab ja on siis: https://verion.aalto.fi/gitlab/api/v4/ (REST API) tai https://version.aalto.fi/gitlab/api/graphql (GraphQL API). Lue lisää rajapintojen käyttöohjeista:

REST APIGraphQL API

Lisää Git-ohjeita

Git-on monipuolinen protokolla versionhallintaan. Sen opetteluun hyvä kirja on Scott Chaconin & Ben Straubin Pro Git. Kirjan sähköinen versio on vapaasti saatavilla osoitteessa: https://git-scm.com/book/en/v2

Versionhallintajärjestelmässä on itsessään myös laaja ohjesivusto osoitteessa: https://version.aalto.fi/gitlab/help